home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / tools / czesc_3 / mrman200 / mrman.doc < prev    next >
Text File  |  1993-03-11  |  13KB  |  332 lines
  1. Copyright (C) 1993 Mark R. Rinfret, MRsoftware
  2.  
  3. Permission is granted to make and distribute verbatim copies of this
  4. manual provided the copyright notice and this permission notice are
  5. preserved on all copies.
  6.  
  7.  
  8. This file documents the `MRMan' manual browser for the Amiga family of
  9. computers.
  10.  
  11.  
  12. Permissions
  13. ************
  14.  
  15. MRMan is freely distributable shareware.  It may be redistributed via
  16. magnetic media or electronic bulletin board systems (BBS).  It is
  17. unlawful to charge a fee for this software other than reasonable
  18. distribution/media fees.
  19.  
  20. The author assumes no responsibilty for damages incurred as a result of
  21. using MRMan.  USE AT YOUR OWN RISK!  No warranties, either expressed or
  22. implied, are made with regard to its use on any system.
  23.  
  24. Once you have tried MRMan and have decided to continue using it, you
  25. are requested to submit five dollars ($5.00 U.S.) to the author.  You
  26. should also provide the following information:
  27.  
  28.          Your mail address
  29.          Your e-mail address(es), if any
  30.          The version of MRMan you are registering
  31.  
  32. Send this to:
  33.  
  34.          MRsoftware
  35.          348 Indian Avenue
  36.          Portsmouth, RI  02871
  37.  
  38.  
  39. Overview
  40. *********
  41.  
  42. MRMan is a document browsing tool for the Amiga family of computers.
  43. Though it borrows part of its name from the Un*x `man' command, it's
  44. actually quite different in its operation.
  45.  
  46. MRMan will let you store your online documents in any location - in a
  47. separate document hierarchy, in multiple hierarchies spread out over
  48. multiple partitions, in the same directories as the associated
  49. programs, etc.
  50.  
  51. MRMan also supports multiple document types and compressed document
  52. files (a la the Un*x-compatible `compress' command). Generally
  53. speaking, MRMan uses the filename suffix (extension following a period)
  54. to distinguish document types. Documents not having an explicit type
  55. (.doc, .text, .guide, etc.) fall into the `default' class. A special
  56. filename suffix, `.Z', is recognized as an indication that the file has
  57. been compressed with the Un*x `compress' program. This compression may
  58. have been performed on a Un*x platform or with an Amiga-compatible
  59. version of the program (available at various Internet sites and in the
  60. Fred Fish library). In this case, the `.Z' suffix is ignored and MRMan
  61. looks for a preceding suffix.
  62.  
  63. MRMan currently relies on two environment variables, `ENV:MRMan/ManPath'
  64. and `ENV:MRMan/Config' to tailor its operation to your system (see
  65. Installing MRMan).
  66.  
  67.  
  68. Installing MRMan
  69. *****************
  70.  
  71. Unpacking the MRMan Archive
  72. ===========================
  73.  
  74. You most likely received MRMan as an Lha archive. It will unpack into
  75. its own directory hierarchy with the following command:
  76.  
  77.      lha -xa x MRMan.lha
  78.  
  79. The actual archive name may vary from `MRMan.lha' since it may include
  80. a version number. If the archive is unpacked correctly, a new directory
  81. will be created containing the MRMan program, documentation and
  82. environment variable directories.
  83.  
  84. Installing the Software
  85. =======================
  86.  
  87. Make the MRMan directory the current directory by using the `CD'
  88. command.
  89.  
  90. You can install the MRMan program in any suitable directory which is a
  91. part of your command search path (i.e. defined by the AmigaDOS `PATH'
  92. command). For example, if you have a directory named `SYS:Bin', you
  93. could copy the MRMan program there with
  94.  
  95.      COPY CLONE MRMan SYS:Bin
  96.  
  97. It is assumed that you have at least one directory on your system where
  98. document files are stored (though this is not a requirement). It is
  99. quite likely that you have several documentation directories (quite
  100. likely not sharing a common hierarchy).
  101.  
  102. The documentation for MRMan comes in three forms:
  103.  
  104.    * A plain text file named `MRMan.doc'
  105.  
  106.    * An AmigaGuide(tm) file named `MRMan.guide'
  107.  
  108.    * A TeX `DVI' file named `MRMan.dvi'.
  109.  
  110. Copy any or all of these to the appropriate online documentation area.
  111.  
  112. Edit the ManPath Environment Variable
  113. =====================================
  114.  
  115. The `ManPath' environment variable is stored in a file in the `MRMan'
  116. installation directory named `Env/MRMan/ManPath'.  This file contains a
  117. list of volume, directory or logical names (not file names) where
  118. online documentation may be found.  The format of this file is one name
  119. per line.  Example:
  120.  
  121.      man:
  122.      uucp:man
  123.      MR0:Debug
  124.      AutoDocs:
  125.  
  126. The `Manpath' environment variable directs MRMan to search in the
  127. specified volumes or directories for documents when building its index.
  128.  
  129. Edit the Config Environment Variable
  130. ====================================
  131.  
  132. The `Config' environment variable is stored in a file in the `MRMan'
  133. installation directory named `Env/MRMan/ManPath'. This file contains
  134. various `MRMan' configuration data which customizes its behavior to
  135. your unique requirements.
  136.  
  137. The `Config' variable appears as a text file with lines of comments
  138. (lines beginning with a semi-colon) interspersed with lines of
  139. directives. The following directives are currently supported:
  140.  
  141.    * index = INDEX_FILE_NAME
  142.      This instructs MRMan to maintain its document index in the file
  143.      specified by INDEX_FILE_NAME.
  144.  
  145.    * defaultviewer = VIEWER_NAME
  146.      This provides the name of a document viewing program, VIEWER_NAME,
  147.      to be used for documents which have no specific type (filename
  148.      suffix).  If the viewer program can always be located via the
  149.      command search path in effect when the `MRMan' command is issued,
  150.      only its simple name must be given.  However, if the viewer
  151.      program is stored in a directory which is not in the command search
  152.      path, the full name must be specified.
  153.  
  154.    * suffix = SUFFIX_NAME VIEWER_NAME
  155.      This directive specifies a legal document file suffix and the name
  156.      of the viewing program which should be used with this file.  If the
  157.      viewer program can always be located via the command search path in
  158.      effect when the `MRMan' command is issued, only its simple name
  159.      must be given.  However, if the viewer program is stored in a
  160.      directory which is not in the command search path, the full name
  161.      must be specified.
  162.  
  163.      ; Define where the MRMan index is stored:
  164.      index = MAN:MRMan.index
  165.      ;
  166.      ; Define the default viewer for filenames which have no suffixes.
  167.      defaultviewer = Multiview
  168.      ;
  169.      ; Declare the legal suffixes for MRMan.
  170.      ; The format for these entries is:
  171.      ;   suffix = <suffix_name> [ <viewer_name> ]
  172.      ;
  173.      ; The suffix name must not include the preceding period.
  174.      ; The <viewer_name> may be either the full name of the viewing program
  175.      ; to be used or a name that is relative to your current search path.
  176.      ;
  177.      suffix = guide  MultiView
  178.      ;
  179.      ; If you don't have MultiView, you might use this entry for
  180.      ; AmigaGuide:
  181.      ;
  182.      ; suffix = guide SYS:Utilities/AmigaGuide
  183.      ;
  184.      suffix = doc    More
  185.      suffix = man    More
  186.      suffix = text   More
  187.      ;
  188.  
  189. Once these changes are made, copy the environment variable directory to
  190. both the ENV: and ENVARC: directories:
  191.  
  192.      COPY CLONE ALL Env ENV:
  193.      COPY CLONE ALL Env ENVARC:
  194.  
  195. Whenever you make changes to your MRMan environment variables, remember
  196. to copy the ENV:MRMan directory to ENVARC:. Otherwise, your changes
  197. will be lost the next time you reboot your system.
  198.  
  199. You're almost ready to use `MRMan', but first, you'll have to build the
  200. index (see Building the Index).
  201.  
  202.  
  203. Building the Index
  204. *******************
  205.  
  206. To speed up `MRMan''s operation, an index of all available online
  207. documentation is built in advance. Presently, this index file is a very
  208. simple flat text file consisting of two fields per line: the subject
  209. name and the full name of the document associated with that subject.
  210. These entries are non-unique. That is, several entries may exist for a
  211. given subject. This topic is discussed in another chapter (see MRMan
  212. Browser Mode).
  213.  
  214. The first time you build the index, you should do it manually to make
  215. sure that you haven't made any typographical errors in your ManPath
  216. environment variable. Just do the following:
  217.  
  218.      mrman VERBOSE INDEX
  219.  
  220. The `VERBOSE' option turns on verbose mode. In verbose mode, `MRMan'
  221. will report every directory scanned and every document file recognized.
  222. The `INDEX' option directs `MRMan' to build the index. Once the index
  223. is built, you can use `MRMan' in its browse mode to locate and view
  224. your online documents.
  225.  
  226. It should be apparent that the `MRMan' index is only as current as you
  227. keep it.  If you add or delete documents but don't rebuild the index,
  228. inaccuracies will result.  MRMan won't know about some documents and
  229. will attempt to locate others that don't exist.  It is highly
  230. recommended that you rebuild the index, either by manually invoking
  231. `MRMan' whenever you make a change to your document set or by running
  232. `MRMan' periodically via an automatic software scheduling program such
  233. as `dcron', `AmiCron' or others. Programs of this type are available
  234. via the Fred Fish library and many bulletin board systems and ftp sites.
  235.  
  236.  
  237. MRMan Browser Mode
  238. *******************
  239.  
  240. `MRMan' has two methods of locating documents:
  241.    * Show documents for specific subject(s) or subject patterns
  242.  
  243.    * Present a 'shopping list' of all available documents
  244.  
  245. Using the first method, MRMan attempts to locate any documents whose
  246. base name (the portion preceding the filename suffix) matches the
  247. desired subject.  You may specify an exactly worded subject (e.g. dos,
  248. enforcer, mrman, etc.) or you may use an AmigaDOS pattern (no directory
  249. components).  If more than one subject matches the pattern, a requester
  250. will pop up and display a list of all documents for which there was a
  251. match.  A single click of the mouse on a list entry will cause the
  252. document to be displayed. Here's an example:
  253.  
  254.      mrman #?graphics#?
  255.  
  256. You should know that MRMan performs a case-insensitive (A=a) comparison
  257. of the pattern you specify against the subjects it finds. You can read
  258. more about AmigaDOS pattern matching in "The AmigaDOS Manual, Third
  259. Edition", chapter 6, "Calling AmigaDOS" under the description for the
  260. MatchFirst function (congratulations to whomever managed to bury this
  261. important information in such an obscure location!).
  262.  
  263. Using the second method, `MRMan' simply presents *all* subjects to the
  264. user in the form of a scrollable list and lets the user pick and choose.
  265.  
  266. To use `MRMan' in the first mode, simply issue a command of the form:
  267.  
  268.      mrman SUBJECT [ ...... SUBJECT ]
  269.  
  270. Notice that more than one subject may be specified in a single
  271. invocation of `MRMan'. For each subject specified, mrman will search
  272. its index and present the associated documentation, using either the
  273. default document viewer or the one specified by the `suffix' directive
  274. (see Installing MRMan) for the document's file type. If the document
  275. was compressed (has a `.Z' suffix), it will first be decompressed to a
  276. temporary file. This temporary file will be deleted once viewing is
  277. terminated.
  278.  
  279. If MRMan should locate more than one document for a given subject, a
  280. pop-up window will open. This window will present a list of all the
  281. documents which were found for the specified subject. The user may
  282. select any of these for viewing simply by clicking the mouse over the
  283. appropriate entry in the scrolling list. When viewing has been
  284. completed, the list reappears. When the user is done viewing all
  285. documentation on the subject, he/she indicates this by clicking on the
  286. `Cancel' gadget near the bottom of the window.
  287.  
  288. To use the 'shopping list' mode, simply invoke `MRMan' without any
  289. arguments:
  290.  
  291.      mrman
  292.  
  293.  
  294. Things to Do
  295. *************
  296.  
  297. I intend to evolve and improve `MRMan' over time.  Your input will be
  298. greatly appreciated.  Some of the changes planned (not necessarily in
  299. any particular order) are:
  300.  
  301.    * More sophisticated index
  302.      While the current approach is adequate for installations having a
  303.      few hundred documents or less online, it probably will suffer on
  304.      much larger systems. I'll probably move toward a hashed lookup
  305.      scheme if someone presents some justification.
  306.      Even nicer would be a "keyword-in-context" index but that may
  307.      result in a major effort.
  308.    * Automatic partial index updating.
  309.      By checking the modification dates on just the document
  310.      directories, `MRMan' could (according to user preferences) update
  311.      just the parts of the index which require changing. Of course,
  312.      this also would require a more sophisticated index structure.
  313.  
  314.  
  315. Concept Index
  316. **************
  317.  
  318.  
  319.  
  320.  Browser Mode                           MRMan Browser Mode
  321.  Browsing All Subjects                  MRMan Browser Mode
  322.  Browsing Specific Subjects             MRMan Browser Mode
  323.  Building the Index                     Building the Index
  324.  Environment Variables                  Overview
  325.  Installation                           Installing MRMan
  326.  Overview                               Overview
  327.  Permissions                            Permissions
  328.  Plans for the Future                   Things to Do
  329.  The Config Environment Variable        Installing MRMan
  330.  The ManPath Environment Variable       Installing MRMan
  331.  
  332.